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Abstract 

The creation of a utility for converting and trans¬ 
forming ambisonic files is described. 

The challenges of making such a utility as indepen¬ 
dent as possible of the user’s platform and of adding 
a GUI to what was initially a command line tool are 
detailed. 

Though the original version was released over a 
year ago, a greatly revised version of Ambisuite 
(ver. 0.6.0) is due to be released to coincide with 
LAC2009. 
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1 Introduction 

Ambisonic 1 files are multi-channel audio files. 
They may, though, contain any number of chan¬ 
nels (from a trivial one or two, but more realisti¬ 
cally from three channels to an infinite number). 

The user of such files is confronted with two 
main problems: 

• Converting from one file format to another 

• Transforming [1] a signal set -for example 
rotating the soundfield 

The utility described uses a Perl [2] script as 
a wrapper to access the functionality of SoX [3] 
to allow such conversions and manipulations. 

1.1 Ambisonic file formats 

1.1.1 Classic formats 

The commonest format for ambisonics files, at 
the time of writing, is a form of wavex (Wave 
Format Extensible), which has a specific GUID 2 
(the equivalent of a UUId) and the suffix .amb. 
The format suffers from two main limitations: 

1 See Appendix (p. 6) for a bried description in rela¬ 
tion to the terms used here. 

2 Acronyms are generally defined on fist occurrence in 

the body of the text. Common ones, which are not, are 

listed/defined in section 6. 


The limit on .wav file size 3 

The non-explicit identification of channels 

For first order ambisonics the first is gener¬ 
ally acceptable (a four channel ambisonic file 
has half the play time of a stereo file at the same 
sampling rate and bit-depth). The latter is cir¬ 
cumvented by restricting usage to the first three 
orders (where channel count can be correlated 
to the format of the signal set 4 ). 

Its great attraction has been the ubiquity of 
applications that handle .wav. Despite that, 
applications that recognise . amb files are few, 
if any, and users have complained of having to 
rename the file (changing the suffix to .wav to 
use files). 

1.1.2 The need for a format to include 
higher order material 

There is an obvious need for a format that does 
not suffer (practical) file size limits and in which 
channels can be explicitly identified. 

From Ambisuite 0.6.0, a . caf format [5] is 
offered with its own specific UUID: 

“5dc3f270c2d24293858e64da38090bea” 
which also has a metadata chunk. This is more 
as ‘proof of concept’ than as a statement that 
this should be the new format. Comments from 
users are invited. 

The same UUID can be used in . wav files (im¬ 
plying an obligatory metadata chunk) allowing 
the same functionality for non-large files. This 
allows the lossless compression of WavPack [6] 
to be exploited. 

3 4GB (though 2GB in some implementations), that is 
about 2 hours of 48KHz/24-bit 4 channel audio. Variants 
allow for a 64-bit hie size description (as against 32) that 
remove this problem for practical purposes (‘W64’ and 
‘RF64’) as does using metadata to chain hies. 

4 See [4]. If more complex mixed-order signal sets 
come into use (e.g. ( H , V, P) sets, see page 6) then the 
situation is more complicated, and these could not all be 
implicitly determined. 



1.1.3 The need for meta-data 

The trial . caf format (and related . wav files) 
use a chunk in XML to store metadata describ¬ 
ing the file content. The dtd at: 

ambisonics.ch/dtds/ambisonic-0.03.dtd 
has been refined after discussion on the Am¬ 
bisonics Association mailing list. 

The dtd countenances files in publica¬ 
tion/exchange format (‘B-format’) as well as 
well as unprocessed microphone signals, the UHJ 
broadcast formats, and ambisonics decoded to 
loudspeaker feeds (so called ‘A-’, ‘C-’ and ‘D- 
format’s). For B-format, of primary relevance 
to Ambisuite, it allows metadata to be stored on 
whether the signal set represents a two-, three-, 
mixed-, etc. dimensional soundfield and the as¬ 
signment of the channels of the file to ambisonic 
channels. It is intended that its style will be able 
to include developments in ambisonics without 
breaking backwards compatibility. 

It has been commented [7] that OSC [8] may 
prove to be a better alternative than XML. 
Though generally associated with dynamic con¬ 
trol of audio, OSC has been used for static con¬ 
figuration files [9]. (There has also been talk - 
no more- of dynamically controlling SoX using 
OSC, which would be very interesting for am¬ 
bisonic usage: for example to alter the aspect 
of (to rotate) a soundfield whilst it is playing.) 

1.2 Ambisonic manipulations 

The basic manipulations (other than adjusting 
amplitude/volume) are rotation and mirroring. 
A yaw (an anti-clockwise rotation about the , 2 - 
axis) is easily achieved for a signal set of any or¬ 
der, likewise mirroring (shake). The other rota¬ 
tions (pitch, roll ) have complicated transforma¬ 
tion matrices and thus far are only implemented 
upto second order. Extension to higher orders 
will be accomplished along with generalised ro¬ 
tations (that is not restricted to the planes of 
the axes). This though is a project for the fu¬ 
ture, indeed it has only just become practicable 
with Franz Zotter’s publication [10] of matrices 
upto twenty-first order, earlier this year. These 
are currently used in shake to allow simple 90° 
step rotations. 

Dominance ([11] p.5: a form of zooming) is 
only possible (for theoretical reasons) for first 
order files ([12] pp. 7-8). 

A mono sound can also be placed at a spe¬ 
cific polar coordinate. The ability to do this 
is limited by the available spherical harmonic 
equations, that is upto sixteenth-order. 


A series of dynamic manipulations are being 
developed, e.g. such that yawing gradually ro¬ 
tates a signal set from one position to another. 

The other manipulations are of niche interest 
and documented in the software (e.g. ambman 
—help=a2b). 


manipulation 

order 

a2b 

1* 

b2a 

1* 

mix 

oo 

normalise 

oo 

pitch 

2 

pitching 

0 

place 

16 

roll 

2 

rolling 

0 

shake 

21 

wxy2amb 

1* 

yaw 

oo 

yawing 

4 


Table 1: Manipulations offered by Ambman. 
The limits marked are the maximum allow¬ 
able by ambisonics, rather than software limits. 
(‘0’ is not yet implemented.) 

2 Implementation 

2.1 Minimal system calls 

As the aim was for universality, then system 
calls have had to be curtailed, and the function¬ 
ality of shell commands not used. Basic file and 
directory operations are carried out using Perl’s 
‘filehandles, files and directories’ functions. The 
only call to Perl’s system function is to SoX and 
all such calls occur through one subroutine to 
ensure systematic error reporting should SoX 
fail (due to lack of discspace, a corrupt input 
file, or whatever). 

2.2 Extensibility 

The aim has been to create ’any-order’ utili¬ 
ties. This meant abandoning classical channel 
sequence and channel weightings (the FuMa or 
Furse-Malham format [13]). That format is only 
applicable to the first three orders (upto six¬ 
teen channels), and its unsystematic approach 
makes software writing both difficult and prone 
to errors. Instead signals are in a normalised 
format (N3D ([14] pp. 155-157, esp. table 3.2 
on p. 156)) and handled in the sequence of their 
ambisonic channel number (acn) [15]. 




ainbcalcu a Perl program that calculates various factors 
relating to Ambisonic files. 

This is an early release for comments, the equations need 
checking and re-checking line-by-line. Do use. Do enjoy. But 
do check for any usage that is critical! — Bug reports are more 
than welcome: ambsuite@mchapman.com . 

Your request was for: 


(45, -45) 


angle = a = 9 = 45 degrees 
elevation = e (= b) = cj> = —45 degrees 


channel 

value 

(dB) 

W 

-3.01 

X 

-6.02 

Y 

-6.02 

Z 

-3.01 

R 

-12.041 

S 

-3.01 

T 

-3.01 

U 

silence 

V 

-6.02 

K 

-15.051 

L 

-5.277 

M 

-5.277 

N 

silence 

O 

-0.737 

P 

-12.041 

Q 

-12.041 


F 

L R 
B 


U 

D 


Tracks in blue italic are inverted relative to W. 


ambcalc is part of the ambisuite collection of software ©2007 Michael Chapman, see program hies 
for details. Ambisonics is a registered trademark of Nimbus Communications International. 

October 12,2007 


Figure 1: PDF output (in FuMa) of Ambcalc. 

2.2.1 Keeping it modular 

The aim has been that all data in the code (e.g. 
‘look up tables’, equations) occur once only and 
then used if necessary by multiple subroutines. 
This eases both error detection and correction. 
All basic code is in a series of subroutines, whilst 
this makes the code verbose, it does facilitate 
later editing. 

2.3 Adding a gui 

At the time of writing a GUI is being developed 
using the Tk toolkit [16] (version 8.5) accessed 
with the Perl Tkx package [17]. Conceptually 
this is quite different from batch processing and 
has resulted in much code having to be rewrit¬ 
ten. (The greatest work has been in having to 
change the promiscuous warning and error mes¬ 
sages that were output to terminal to systematic 
ones that could be rendered on either terminal 
or GUI.) 

It is an exciting challenge, and one that is 
probably essential if Ambisuite is to reach musi¬ 
cians, composers and others who may be averse 
to command line syntax. 


3 Usage 

Whilst not the prime purpose of this paper, it 
would be remiss not to give a brief guide to using 
the utilities. 

The compressed bundle can simply be opened 
in a directory and used there. To get the max¬ 
imum benefit they should be installed (with 
root privileges) and then can be used any¬ 
where. All the *.pl files (except libambisuite.pl) 
should be moved to a directory on the users’ 
search paths (/bin/ works fine on most sys¬ 
tems). Renaming them by dropping the suffix 
(e.g. cp ambman.pl /bin/ambman) makes for 
easier use, and the GUI script can be renamed 
(i.e. cp ambisuite-gui.pl /bin/ambisuite). 
Permissions should already allow for execution 
but can easily be changed if necessary (e.g. 
chmod 755 /bin/ambman). 

The library of sub-routines (libambisuite.pl) 
needs to be in Perl’s search path (and should 
not be renamed). Trying to execute a mythical 
Perl program will cause Perl to list its search 
path (e.g. perl -e ’require "zyxw.pl";’), 
and one of the listed directories can then be 
used as a location for ambisuite.pl. (E.g. 
/usr/lib/per15/vendor_perl/.) 

The utilities can then be called in a terminal. 
Calling without options will give basic usage in¬ 
formation, or they can be called with the option 
—help. (Sample terminal outputs for informa¬ 
tional utilities are in figures 2, 3, 4 and 5.) As 
yet there is no icon for opening the GUI, but typ¬ 
ing ambisuite and then RETURN in a terminal 
will bring up the introductory window. 

]$ ambcalc 

AMBCALC 0.5.3, 2007/09/18 - Copyright (c) 2007 by Michael 

This is an early release for comments, the equations need 
checking and re-checking. Do use. Do enjoy. But do check 

for any usage that is critical! - Bug reports are more 

than welcome: ambsuite@mchapman.com 

type q to quit, h for help 

angle (a): 45 
elevation (e): -45 
channel i value ( dB ) 


W -3.01 

X -6.02 

Y -6.02 

Z - -3.01 


A in the "i" column indicates the track is inverted 
relative to the W track (that is the amplitude is 
negative). 


Figure 2: Terminal output (in FuMa) of Amb¬ 
calc. 















] $ ambchan hv=4,2 

AMBCHAN 0.5.3, 2008/09/18 - Copyright (c) 2008 by Mich 

Channels for (H,V) = (4,2): 

(Malham notation = ffhh.) 

0,1, 2, 3, 4, 5, 6, 7, 8, 9, 15, 16, 24 
Total channels used = 13. 

1 m ACN 

0 0 0 
1-11 
10 2 
113 
2-2 4 

2- 15 

2 0 6 

2 17 
2 2 8 

3- 3 9 

3 3 15 

4 -4 16 

4 4 24 

Figure 3: Terminal output of Ambchan, giving 
channels in a (h, v ) = (4,2) file. 

]$ ambchan R 

AMBCHAN 0.5.3, 2008/09/18 - Copyright (c) 2008 by 
AMBIS0NIC CHANNEL: 

6 -ambisonic channel number (ACN) 

2,0 -(l,m) — (order,range) 

R -channel letter (if appropriate). 

The formula for the spherical harmonic associated 
with this second degree component can be found at: 
http://ambisonics.ch/standards/channels/ACN6 

Figure 4: Terminal output of Ambchan, giving 
synonyms for channel R. 

]$ ambinfo MC_26-positions.amb 

AMBINF0 0.5.4, 2008/10/31 - Copyright (c) 2007-8 by Michael 

SUMMARY; (run with -v for more details) 

Channels: 4 

Implicitly a first order file 
channels (I am guessing) are WXYZ 

48 KHz / 24 bits / PCM / AMBISONIC 

estimated duration 130 seconds: 

Figure 5: Terminal output of Ambinfo. 

4 The Future 

There is still much work to be done, even in 
getting the present features running smoothly. 
User feedback is welcomed to assist with that 
process. 

Whilst a ‘modern’ file format has been pro¬ 
posed in the present release of Ambisuite, this 
is there very much as an example of how things 


may be. 5 If the ambisonic community can come 
together behind a file format, that will need in¬ 
corporating. Most of the coding is though al¬ 
ready there and adding a new format should 
now be relatively easy. 

The question of mixed-order files (see page 6) 
is somewhat unstable at present. Ambisuite 
supports classical mixed order files, described 
by order (highest degree) and highest peri- 
phonic degree. The dtd has scope for a third in¬ 
teger if/when more complex sets of mixed chan¬ 
nels are standardised. 

The author [12] has a personal interest in hy- 
perambisonics (the manipulation of four-, five¬ 
dimensional, etc. soundfields) and the experi¬ 
mental code for this should be added, once ti¬ 
died. 
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6 Acronyms 

Acronyms are generally defined in the text. The 
commoner ones, which are not, are defined here. 

DTD Document Type Definition [18] 

GUI graphical user interface (a win- 
dow/icon/mouse/pointer access to a program, 
rather than a terminal) 

GUID globally unique identifier (Microsoft’s 
implementation of uuids). 

N3D [14], pp. 155-157, esp. table 3.2 on p. 156 

PDF Adobe’s Portable Document Format 

UUID universally unique identifier (man 
uuidgen for basic information. 

5 Man is the only animal that can both laugh and cry: 
for he can see both how things are and how they might 
have been. 



XML Extensible Markup Language [18] 
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Appendices 

Download and licence 

Ambisuite consists of a GUI called by the com¬ 
mand ambisuite, and command line utilities: 

ambman —the basic manipulation (conver¬ 
sion and transformation) program 

ambcalc — prints out channel values for a 
given azimuth and elevation 

ambchan converts channel 

names/notations, and likewise for 
groups of channels 

ambinfo — reads a WAVEX header and 
outputs to terminal 

amb2caf — converts a classic . amb file to a 
. caf file with metadata 

wav2amb — ‘corrects’ the headers on Wave 
Format Extensible files creating a 
. amb file 

It has a recent Sourceforge page 

(http://ambisuite.sourceforge.net/) 



though most of the material still resides at 
http://mchapman.com/amb/soft/index. The 
Sourceforge site 6 also contains the ‘forum’ for 
help, bug reports and feature requests. 

It requires Perl (almost any version) for all 
operations, the audio manipulations require 
SoX (latest version) and the GUI requires the 
Tk toolkit and Perl Tkx (see above for refer¬ 
ences giving URLs). 

Ambcalc will present a nice pdf output (see 
figure 1) as well as the terminal output. (A 
DT^X file is optionally produced and can be pro¬ 
cessed with pdflatex or similar.). 


utility 

Perl 

SoX 

ambrnan 

yes 

yes 

ambcalc 

yes 

no 

ambchan 

yes 

no 

ambinfo 

yes 

no 

amb2caf 

yes 

yes 

wav2amb 

yes 

yes 


Table 2: Dependencies 


It is released under the GNU General Public 
License, version 3. 

Note 

This paper was written as some of the code was being 
finalised. The released version 0.6.0 may show some 
slight variation. (Screenshots, etc. are from version 
0.5.*.) 

Ambisonics 

Unfortunately it is difficult to give an appropri¬ 
ate reference explaining basic ambisonics. Mal- 
ham [13] though excellent covers material most 
likely well known to most ambisonic users. For 
the newcomer, reading this paper, the differ¬ 
ences in channel notation, sequence and weight¬ 
ings is likely to be a hurdle. 

The basics used here are explained below. 

channels 

An ambisonics signal set represents sound from 
all directions. That is from the full 360° for 
two dimensions ( pantophony ) or a full sphere 
( periphony ). Hybrids of these are possible (see 
Mixed Order Sets below.) The accuracy of 
the representation is increased by adding more 
channels, these are added in discrete groups or 
degree s. 

(j https: //sourceforge .net/forum/forum.php?forum_ 
id=898927. 


The fact that a full soundfield is represented, 
means that transformations [1] -such as rotat¬ 
ing the soundfield- are possible. 

An ambisonic signal set is described as being 
of a certain order. 7 

Zero-order is possible, it comprises one chan¬ 
nel and is effectively omni-directional mono. 

For practical ambisonic files it is necessary to 
add first- (second-, etc) degree signals. Thus 
a third-order file contains zero-, first-, second- 
and third-degree signals. 

For pantophony each additional degree con¬ 
sists of two channels. So the channel count is 
21 + 1, where l is the order. 

For periphony the number of channels in each 
degree is different (3, 5, 7, . ..) and the channel 
count is (Z + l) 2 . 

The channels within a degree are referred to 
by their order (not to be confused with am¬ 
bisonic order) m, with — l > m > l. Panto- 
phonic sets only contain channels with m = +/. 
It is convenient to give a unique integer to each 
channel (not least for ordering them in a file), 
the ambisonic channel number (acn), given by 
Z(Z + 1) + m. 

Acns 0 to 15 correspond, respectively, 
to the FuMa letter codes W YZX VTRSU 
QOMKLNP. (There are no letter codes for 
higher channels. FuMa also applies a (non- 
normalised) ’weighting’ (an amplitude factor) to 
each channel [13]). 

A generalised notation for channels uses l and 
m, with each channel designated R™. If acns 
are used the simpler B n where n is the ACN can 
be used. 

mixed order sets 

Traditionally mixed order signal sets have the 
lower degree(s) in periphony and the higher 
one(s) in pantophony. This gives accurate hor¬ 
izontal representation and a more limited rep¬ 
resentation of ‘height’ information. This corre¬ 
sponds with the soundstage for performed mu¬ 
sic. 

Classically these were periphonic (three- 
dimensional in lower degrees) with pantophony 
in higher degrees. Ambisuite (and the dtd it 
uses) currently recognises this system. However 
other mixes are possible, for example second- 
order with all components except channel 6 
( R ). This eight channel signal set is all that is 

7 Here order refers to the entire signal set/file, whilst 
degree refers to each spherical harmonic degree. Pre¬ 
viously order has been used by some authors for both 
terms. 




needed, for example, for playback on a cuboidal 
rig 8 and also has the convenience of being loss- 
lessly compressible in a FLAC file. These more 
complex mixed order sets need three integers to 
describe them. The current favoured notation is 
(. H,V,P ), though this remains to be standard¬ 
ised and published. 

For a more detailed explanation of these sig¬ 
nal set terms, and their usage see Cotterell & 
Chapman [1], 


8 Channel 6 is a “discarded ambiguous har¬ 
monic”, see Richard Furse’s First and Sec¬ 
ond Order Ambisonic Decoding Equations (at 
www.muse.demon.co.uk/ref/speakers.html) (and 

unlike channel 8 (U) has no potential use if it is desired 
to yaw the soundfield.) 



